home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / dev / debug / sushi37_7.lzh / sushi.doc < prev   
Text File  |  1993-02-23  |  12KB  |  393 lines
  1. sushi v37.7
  2.  
  3. Copyright (c) 1992 Commodore-Amiga, Inc.  All Rights Reserved
  4.  
  5. Sushi - intercepts raw serial debugging output on your own machine
  6.  
  7. startup options:  [ON] [BUFK=n (power of 2 only)] [NOPROMPT] [QUIET] [ASKSAVE]
  8. runtime options:  [OFF] [SAVE] [SAVEAS filename] [EMPTY]
  9.  
  10. by Carolyn Scheppner - CATS
  11.  
  12.  
  13. Thanks to Steve Tibbett and Christian E. Hopps for their own
  14. implementations, "Reporter" and "Detective", which made me insatiably
  15. curious and drove me to write my own.
  16.  
  17. Sushi is a tool to intercept the raw serial output of Enforcer 2.8b,
  18. Enforcer.megastack 26.f, Mungwall, and all tool and application debugging
  19. output that uses kprintf.  This makes it possible to use serial debugging
  20. on a single Amiga, without interfering with attached serial hardware
  21. such as modems and serial printers.  Sushi also provides optional
  22. signalling and buffer access to an external display/watcher program.
  23.  
  24.  
  25. QUICK USAGE
  26. ===========
  27. Here's what's in my user-startup:
  28.  
  29. run >NIL: mungwall NAMETAG
  30. ; NOTE - with upcoming Enforcer 37.x, instead use: run >NIL: ENFORCER RAWIO 
  31. enforcer >NIL:
  32. run >NIL: sushi <>"CON:0/20/640/100/Sushi  CTRL-E=Empty  CTRL-F=File/AUTO/CLOSE/WAIT/INACTIVE" ON BUFK=64 NOPROMPT
  33.  
  34.  
  35. If Sushi can find Enforcer 2.8b, or 2.6f megastack resident, then it
  36. can patch these Enforcers to redirect their output.  Other debugging
  37. output is intercepted by patching low level debugging output functions.
  38. Upcoming versions of Enforcer (37.x) can not be found and patched in the
  39. same way by Sushi (they have no port) - howvever, if you use the RAWIO
  40. option of new 37.x Enforcer versions, Sushi will catch their output.
  41.  
  42. All standard serial debugging functions are intercepted.  Currently,
  43. the patch to the serial debugging input function just returns a 'y'.
  44. Standard serial debugging output and Enforver output go into sushi's
  45. circular buffer (user-definable size, default 32K), where it is noticed
  46. by the Sushi process and written to stdout.  The Sushi process is signalled
  47. whenever a carriage return or linefeed comes through kprintf.
  48.  
  49. if Enforcer 2.8b or 2.6f has been found and patched, Sushi will also
  50. wake up every 1/10 second to check for output in its buffer (since it
  51. is not safe for Sushi's Enforcer wedge to signal Sushi's process during
  52. an Enforcer bus error).  If you are not using Enforcer 2.8b or 2.6f but
  53. you still want Sushi to wake up every 1/10 second to check for output
  54. (instead of only waking up on carriage returns and linefeeds), then pass
  55. the special hidden command line option "TimerOn" when you start up Sushi.
  56.  
  57. Sushi's standard output can be redirected elsewhere (for example, to
  58. a multiserial handler or an AUTO/WAIT/CLOSE CON window).  Or Sushi can
  59. be run in QUIET mode and external watcher/display tool can be signalled
  60. by Sushi for more elaborate display of the output.  (i.e. If you personally
  61. want your machine to MOO when you get a mungwall hit, and flash purple
  62. polka dots for Enforcer hits, you can write an external sushi watcher
  63. or display tool to do that).
  64.  
  65.  
  66. Sushi has several startup options, and several runtime options:
  67.  
  68. startup options:  [ON] [BUFK=n (power of 2 only)] [NOPROMPT] [QUIET] [ASKSAVE]
  69.           [TIMERON]
  70. runtime options:  [OFF] [SAVE] [SAVEAS filename] [EMPTY]
  71.  
  72.  
  73. Startup Options
  74. ===============
  75. ON        Default (not required)
  76.  
  77. BUFK=n        Changes circular buffer size from default 32K to specified
  78.         power-of-2 K from 4K to 2028K.  Sushi will always round
  79.         the specified size down to a power of two K (32K, 64K, etc).
  80.  
  81. NOPROMPT    Turns off the "sushi installed" and "enforcer not found"
  82.         prompts.  Useful if redirecting sushi to an AUTO CON
  83.         window in your user-startup.
  84.  
  85. QUIET        Causes Sushi to just buffer all debugging output.
  86.         Effectively silences serial debugging output.
  87.         Useful in conjunction with an external sushi watcher
  88.         or displayer (see later explanation).
  89.  
  90. ASKSAVE        Cause Sushi to ask you if you want to save the buffer
  91.         when you exit Sushi.  If there's nothing in the buffer,
  92.         it won't ask.  Make SURE sushi has a stdin if you
  93.         use this option.  If sushi thinks it has no stdin,
  94.         it will save to t:sushi.out.
  95.  
  96. TIMERON        Cause Sushi to wake up every 1/10 second to check for
  97.         output even if Enforcer 2.8b or 2.6f have not been patched.
  98.         Without this option, Sushi will just wake up every time a
  99.         carriage return or linefeed is output.
  100.  
  101.  
  102. Runtime Options
  103. ===============
  104. OFF        Signals active running copy of Sushi to exit (CTRL_C)
  105.  
  106. EMPTY        Signals active running copy of Sushi to empty its buffer.
  107.  
  108. SAVE        Finds active running copy of Sushi and saves its buffer
  109.         as t:sushi.out
  110.  
  111. SAVEAS name    Finds active running copy of Sushi and saves its buffer
  112.         as specified filename
  113.  
  114.  
  115.  
  116.  
  117. Example Startup Usage
  118. =====================
  119.  
  120. sushi ASKSAVE    (in its own shell window)
  121.  
  122. run >NIL: sushi  >"CON:0/20/640/120/Sushi/AUTO/CLOSE/WAIT" ON NOPROMPT INACTIVE
  123.  
  124. run >NIL: sushi <>"CON:0/20/640/120/Sushi/AUTO/CLOSE/WAIT" ON NOPROMPT INACTIVE
  125.  
  126.    NOTE !!!  The double redirection as above (<>) works with Amiga CON:
  127.    V37 or higher.  It may not work with some third-party CON's.
  128.    The ASKSAVE option requires input from the CON window.
  129.  
  130. run sushi >ram:hits (all output redirected to a file)
  131.  
  132. run sushi NOPROMPT QUIET    (for use with external displayer)
  133.  
  134. NOTE: You may want use the following title for a sushi AUTO CON window:
  135.     /Sushi   CTRL-E:Empty   CTRL-F:File/
  136.  
  137.  
  138. Keyboard and BREAK signals
  139. ==========================
  140. CTRL-C: To quit Sushi, CTRL-C it (if it has its own window), send it
  141.     a CTRL-C with the c:BREAK command, or run sushi a second time
  142.     with the OFF keyword.
  143.  
  144. CTRL-E: Tells Sushi to empty (clear) its buffer.
  145.  
  146. CTRL-F: Tells Sushi to save its own buffer to file t:sushi.out
  147.  
  148.  
  149. Other Runtime Usage
  150. ===================
  151. sushi OFF            ; tell active running Sushi to try to exit
  152. sushi SAVE            ; save buffer of active Sushi
  153. sushi SAVEAS ram:myhits EMPTY   ; save buffer as ram:myhits and clear buffer
  154.  
  155. Usually, I just CTRL-F in the Sushi window, and it saves its buffer as
  156. t:sushi.out.
  157.  
  158.  
  159. Programmer Interface
  160. ====================
  161.  
  162. Sushi allows a external tasks to find and read its buffer, and allows
  163. one external task to register itself to be signalled by Sushi
  164. whenever there is new information in the buffer.  Sushi will refuse
  165. to exit as long as a task is registered with it.  So make sure
  166. you remove your pointer from Sushi's port before you exit !!!!
  167.  
  168. Here is an example that finds Sushi and installs itself as the
  169. external sigtask.  Sushi will signal this task whenever there
  170. is new information in sushi's buffer.
  171.  
  172. The example also shows (ifdef'd out)  how to ask Sushi to
  173. write its buffer, flush its buffer, or exit.
  174.  
  175.  
  176.  
  177. ;/* ext_sushi.c - Execute me to compile me with SAS C 5.10
  178. LC -b1 -cfistq -v -y -j73 ext_sushi.c
  179. Blink FROM LIB:c.o,ext_sushi.o TO ext_sushi LIBRARY LIB:LC.lib,LIB:Amiga.lib
  180. quit
  181.  
  182. ext_sushi.c - An example of an external display or watcher program
  183.         which is signalled by sushi.
  184. */
  185.  
  186. #include <exec/types.h>
  187. #include <exec/memory.h>
  188. #include <libraries/dos.h>
  189.  
  190. #include <clib/exec_protos.h>
  191. #include <clib/dos_protos.h>
  192. #include <stdlib.h>
  193. #include <stdio.h>
  194. #include <string.h>
  195.  
  196. #ifdef LATTICE
  197. int CXBRK(void)  { return(0); }  /* Disable Lattice CTRL/C handling */
  198. void chkabort(void) { return; }  /* really */
  199.  
  200. extern struct Library *SysBase;
  201. extern struct Library *DOSBase;
  202. #include "pragmas/exec_pragmas.h"
  203. #include "pragmas/dos_pragmas.h"
  204. #endif
  205.  
  206.  
  207. #define MINARGS 1
  208.  
  209. UBYTE *vers = "\0$VER: ext_sushi 37.2";
  210. UBYTE *Copyright = 
  211.   "ext_sushi v37.2\nCopyright (c) 1992 Commodore-Amiga, Inc.  All Rights Reserved";
  212. UBYTE *usage = "Usage: ext_sushi";
  213.  
  214.  
  215. void bye(UBYTE *s, int e);
  216. void cleanup(void);
  217.  
  218.  
  219. UBYTE sushiname[] = "sushi_CAS_port";
  220.  
  221. /* Definitions of WTP and AppStruct structures */
  222.  
  223. struct AppStruct {
  224.    /* These are for READ-ONLY use by external application */
  225.    UBYTE    *subuf;        /* Sushi's circular output buffer */
  226.    ULONG    subufsize;    /* Size of buffer in bytes (a power of 2K) */
  227.    ULONG    subufi;        /* Where Sushi will place next char received */
  228.    ULONG    subufli;    /* Sushi's local index of what it has processed */
  229.    ULONG    wrapcnt;    /* How may times circular buffer has wrapped */ 
  230.    ULONG    wrapmask;    /* Hex mask Sushi uses when wrapping subufi */
  231.  
  232.    /* External app writes to these if not in use; must clear them before exiting */
  233.    struct Task    *extsigtask;
  234.    LONG        extsignum;
  235.    ULONG    extsignal;
  236.  
  237.    /* Microseconds that Sushi waits between checking for Enforcer hits.
  238.     * Default is 100000 (1/10 sec).  If you find it necessary to touch this,
  239.     * BE REASONABLE - and PUT BACK THE DEFAULT before you exit !!!!
  240.     * Note that Sushi itself is Signalled for all other debugging output
  241.     * any time a CR or LF is placed in buffer.  Sushi will only signal
  242.     * the external task if there is actually something in the buffer.
  243.     */
  244.    ULONG    sumicros;
  245.  
  246.    /* private stuff here - subject to moving since any additional
  247.     * public things will be added right here.
  248.     */
  249.    };
  250.  
  251.  
  252. /* Sushi's public named port - contains pointer to AppStruct above */
  253. struct WTP {
  254.    struct MsgPort wtPort;
  255.    struct AppStruct *appstruct;
  256.    /* private stuff here - subject to moving since any additional
  257.     * public things will be added right here.
  258.     */
  259.    };
  260.  
  261. struct  WTP      *wtp = NULL;
  262. struct  AppStruct *aps = NULL;
  263. LONG    sushisignum  = -1;
  264. BOOL    GotSushi     = FALSE;
  265.  
  266.  
  267. void main(int argc, char **argv)
  268.     {
  269.     struct  Task     *mytask;
  270.     UBYTE           *buf;    
  271.     ULONG   sushisignal, signals, bufi, bufli; 
  272.     BOOL    Done;
  273.  
  274.     if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
  275.     {
  276.     printf("%s\n%s\n",Copyright,usage);
  277.     bye("",RETURN_OK);
  278.     }
  279.  
  280.     bufli = 0;        /* this application's last index into sushi buffer */
  281.     mytask = FindTask(NULL);
  282.     GotSushi = FALSE;
  283.  
  284.     Forbid();
  285.     if (wtp = FindPort(sushiname))
  286.         {
  287.     aps = wtp->appstruct;
  288.         if(! aps->extsigtask)    /* You MUST not install if someone else has */
  289.         {
  290.             if((sushisignum = AllocSignal(-1)) != -1)
  291.             {
  292.             sushisignal     = 1L << sushisignum;
  293.  
  294.             aps->extsigtask    = mytask;
  295.             aps->extsignum     = sushisignum;
  296.             aps->extsignal    = sushisignal;
  297.         buf         = aps->subuf;
  298.             GotSushi     = TRUE;
  299.             }
  300.         }
  301.         }
  302.     Permit();
  303.  
  304.     if(!GotSushi)
  305.     bye("Can't allocate sushi - not found or in use\n", RETURN_FAIL);
  306.  
  307.     Done = FALSE;
  308.  
  309.     while(!Done)
  310.         {
  311.         signals = Wait( SIGBREAKF_CTRL_C | sushisignal );
  312.  
  313.         /* Make sure you turn off your compiler's CTRL-C handling
  314.           * if you use CTRL-C as your exit signal.
  315.           */
  316.         if( signals & SIGBREAKF_CTRL_C)
  317.         {
  318.         Done = TRUE;
  319.         }
  320.  
  321.         if(signals & sushisignal)
  322.         {
  323.         /* There's some new info in the sushi buffer.
  324.          * Here we will just print it out.
  325.          * You could instead copy it elsewhere for fancy display, etc.
  326.          */
  327.         bufi = aps->subufi;    /* grab where sushi has filled to */
  328.         
  329.         if(bufi > bufli)        /* buffer has not wrapped since last */
  330.         {
  331.         Write(Output(),&buf[bufli],bufi - bufli);
  332.         }
  333.         else if(bufli > bufi)    /* buffer has wrapped since last */        
  334.         {
  335.         /* Write end of buffer info, then new info at start of buffer */
  336.         Write(Output(),&buf[bufli],aps->subufsize - bufli);
  337.         Write(Output(),buf,bufi);
  338.         }
  339.         /* Update variable that saves where YOU are up to */
  340.         bufli = bufi;
  341.         }
  342.  
  343. #if 0
  344.     /* FYI - Other things you can tell Sushi to do */
  345.  
  346.     /* Tell Sushi to write its buffer as file t:sushi.out.
  347.      * Sushi writes its buffer in chronological order -
  348.      * i.e., if the buffer has wrapped, it writes older end of buffer,
  349.      * then writes data from start of buffer to current position.
  350.      */
  351.     Signal(aps->sutask, SIGBREAKF_CTRL_F);
  352.  
  353.     /* Tell Sushi to empty (clear) its buffer (i.e. reset its indexes).
  354.      * If you do this, you should probably reset your bufli to 0.
  355.      */
  356.     Signal(aps->sutask, SIGBREAKF_CTRL_E);
  357.  
  358.     /* Tell Sushi to exit if it can.
  359.      * It can not exit if there is an aps->extsigtask.
  360.      */
  361.     Signal(aps->sutask, SIGBREAKF_CTRL_C);
  362.  
  363. #endif
  364.  
  365.         }
  366.     bye("",RETURN_OK);    /* Will do Sushi and other cleanup */
  367.     }
  368.  
  369.  
  370. void bye(UBYTE *s, int e)
  371.     {
  372.     cleanup();
  373.     exit(e);
  374.     }
  375.  
  376.  
  377. void cleanup()
  378.     {
  379.     /* Required cleanup for external sushi program before exiting ! */
  380.     if(GotSushi && (aps != NULL))
  381.     {
  382.     /* Required Sushi cleanup before you exit !!!! */
  383.     Forbid();
  384.     aps->extsignum  = 0L;
  385.     aps->extsignal  = 0L;
  386.     aps->extsigtask = NULL;
  387.     Permit();
  388.     }
  389.     if(sushisignum != -1)    FreeSignal(sushisignum);
  390.     }
  391.  
  392.  
  393.